\ 92a) Ry 
Ss Seen 


QL Assembly Language Mailing L 


Issue 6 


Norman Dunbar 


TIO 
Dee 


Gg 
ay 

Y 
Cy pe 


Cs 
° 


4 


PUBLISHED BY MEMYSELFEYE PUBLISHING ;-) 


Download from: 
https: //github.com/NormanDunbar/QLAssemblyLanguageMagazine/blob/Issue_006/Issue_ 
006/Assembly_Language_006. pdf 


Licence: 

Licensed under the Creative Commons Attribution-NonCommercial 3.0 Unported License (the 
“License”’). You may not use this file except in compliance with the License. You may obtain a 
copy of the License at http: //creativecommons.org/licenses/by-nc/3.0. Unless required 
by applicable law or agreed to in writing, software distributed under the License is distributed on an 
“AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
See the License for the specific language governing permissions and limitations under the License. 


This pdf document was created on 15/12/2018 at 14:34:38. 
Copyright ©2018 Norman Dunbar 


2.1 


3.0.1 
3.0.2 
3.0.3 


4.1 
4.1.1 
4.1.2 
4.2 
4.2.] 


of 


I= 


VBR -vector Base Register... eens 21 
CAGR arial CAAR = Cache CON cca ccc Awan ce ow woud ck va nw aes 2] 
USP MSP and ISP - Stack Pointers 2... 0... 0. cc ees 21 


WSS RG 65 ett ststr estore disest ners bre rents 23 


Feedback 


Please send all feedback to . You may also send articles 
to this address, however, please note that anything sent to this email address may be used in a future 
issue of the eMagazine. Please mark your email clearly if you do not wish this to happen. 


This eMagazine is created in 4IRXsource format, aka plain text with a few formatting commands 
thrown in for good measure, so I can cope with almost any format you might want to send me. As 
long as I can get plain text out of it, I can convert it to a suitable source format with reasonable ease. 


I use a Linux system to generate this eMagazine so I can read most, if not all, Word or MS Office 
documents, Quill, Plain text, email etc formats. Text87 might be a problem though! 


Subscribing to The Mailing List 


This eMagazine is available by subscribing to the mailing list. You do this by sending your 
favourite browser to and clicking on the 
link “Subscribe to our Newsletters”. 


On the next screen, you are invited to enter your email address twice, and your name. If you wish 
to receive emails from the mailing list in HTML format then tick the box that offers you that option. 
Click the Subscribe button. 


An email will be sent to you with a link that you must click on to confirm your subscription. Once 
done, that is all you need to do. The rest is up to me! 
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1.3 Contacting The Mailing List 


I’m rather hoping that this mailing list will not be a one-way affair, like QL Today appeared to be. 
I’m very open to suggestions, opinions, articles etc from my readers, otherwise how do I know 
what I’m doing is right or wrong? 


I suspect George will continue to keep me correct on matters where I get stuff completely wrong, as 
before, and I know George did ask if the list would be contactable, so I’ve set up an email address 
for the list, so that you can make comments etc as you wish. The email address is: 


assembly@qdosmsq.dunbar-it.co.uk 


Any emails sent there will eventually find me. Please note, anything sent to that email address will 
be considered for publication, so I would appreciate your name at the very least if you intend to 
send something. If you do not wish your email to be considered for publication, please mark it 
clearly as such, thanks. I look forward to hearing from you all, from time to time. 


If you do have an article to contribute, I'll happily accept it in almost any format - email, text, Word, 
Libre/Open Office odt, Quill, PC Quill, etc etc. Ideally, a IATRXsource document is the best format, 
because I can simply include those directly, but I doubt I'll be getting many of those! But not to 
worry, if you have something, I'll hopefully manage to include it. 
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No Feedback so far! 


Recently, I’ve been playing about with the xtc68 C compiler - which is basically C68 for Linux 
(or Windows, if you must!) and allows me to have fun writing C68 programs on my Linux laptop, 
which will be eventually copied over to the QL, and executed there. 


As ever, any computer that is not a QL (or an emulator) has a problem when executable files are 
involved - there’s no file header present, so there’s no easy way to make the file executable on the 
QL - other than making up some number for the data space, allocating a chunk of RAM equal to 
the file size, loading it into that RAM area with LBYTES and then SEXECing the file back to the 
device. There has to be an easier way, surely? 


I started a thread on QLForum about this cross compiler, and somewhere in that thread, I put up 
the code for a SuperBasic utility to fix up the dataspace for these compiled files. The forum thread 
is at . However, it wasn’t quite what I 
really needed, plus, I couldn’t really write an article for the eComic if the code was in SuperBASIC, 
could I? 


Step forward my XTcc utility, described later. This utility does all the needful to get a file on the 
QL from its unusable state to a executable - very handy for files compiled with the xtc68 compiler 
or anything else that writes an XTcc trailer to the compiled file. I only know of the xtc68 compiler 
which does this, but there may be others. (Feedback very welcome.) 


The XTcc Trailer Record 


The trailer record produced by the compiler, and any other applications that create it, is a simple 
addition of 8 bytes to the very end of the file in question. These 8 bytes are split into two 4 byte 
chunks: 


e The text “XTcc” in exactly that letter case. 
e The required data space for the QL file, in big endian, long word format. 
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3.0.2 Program Description 


The program, XTcc, is quite simple and carries out the following steps after being executed as a 
filter: 


e Checks that only one filename was supplied, exits with a Bad Parameter error if not. 
Reads the file’s header. 

If the file is already an executable file, then exits quietly as there is nothing more to do. 
Reads the file’s length from the header, and sets the file pointer to that position minus 8 bytes. 
If the file cannot be positions at the required place, exit with an Out of Range error. 
Reads the last 8 bytes of the file. Exits with a File Error if 8 bytes couldn’t be read. 
Checks that the first 4 bytes read are "XTcc", if not, exits with a Not Found error. 
Copies the data space from the last 4 bytes of the file into the file header. 

Sets the file’s type, in the header, to be executable. 

Writes the file header back to the medium. 

The job then exits as if nothing had happened. 


3.0.3 The Program Listing 
lf; 
2 Eieeeclices 
3h; 
4}; This utility reads a cross—compiled executable for QDOSMSQ and will 
5; attempt to correctly set the file ’s data space according to the 
6 Ie ice Vsecttimemstoned Mate thie send sol Ss thicu mice 
TE; 
8a; 


9; EX XTcc_bin, input_file 


129}; 13/12/2018 NDunbar Created for QDOSMSQ Assembly Mailing List. 


149}; (c) Norman Dunbar, 2018. Permission granted for unlimited use 
159}; or abuse, without attribution being required. Just enjoy! 
16§; 


Listing 3.1: XTcc - Comments 


Nothing to see here except some blurb explaining what the code is for and how to execute the 


utility. 
17 
18}; How many channels do I want? 
19 |) NUMCHANS 
20 equ 1 ; How many channels required? 
21 
22 


Yea |> Stipek Simin . 
24) sourceld 
25 equ $02 5 OwiseiCay) to mmpmt iwile ne 


27 Other ssturt. 

28 f err_nc 

27 equ —1 ; Not complete. 
30 f err_or 


equ 
err_nf 

equ 
err_bp 

equ 
err_fe 

equ 
timeout 

equ 
me 

equ 
exeType 

equ 
fileType 

equ 
fileSize 

equ 
fileData 

equ 


$06 : 


Out of range. 
Not found. 

Bad parameter. 
File wennone 


Trap call timeouts. 


Jobeid ion st his job 


Fille Iie TOr Sxeewialille. 


OWSEE im Ingacler jo iruille 


type 


Otiset von tile leneth= 


Offset to dataspace in header 


Listing 3.2: XTcc - Equates 


The code above simply initialises various equates that will be required elsewhere. 


; Here begins 


the code. 


Slack mone Nitty 


if odd length. 


13/Dec/2018’ 


Storage for file header 


; $0c(a7) = bytes of parameter + padding , 
; $0a(a7) = Parameter size word. 
; $06(a7) = Output file ichianniell id= 
 S02\(al =" Sounce fille channel! vide 
; $00(a7) = How many channels? Should be $02. 
start 

bra.s checkStack 

dc.l $00 

dc.w $4afb 
name 

dc.w name_end—name—2 

dc.b AMEE * 
name_end 

equ * 
version 

dc.w vers_end—version —2 

dc.b >Version 1.00 — 
vers_end 

equ * 
rh_buffer 

ds .w 32 z 
xtcc_buffer 

ds.l 2 : 


Storage for XTcc flag * 


83 
84 
85 
86 
87 
88 
89 
90 
91 
a2 
3 


94 
a5 
96 
97 
98 
99 
100 
101 
102 
103 
104 
105 
106 
107 


108 
109 
110 
111 
112 
11s 
114 
Ls 
116 
117 
118 
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——dataspacie 


Listing 3.3: XTcc - Job Start 


Now we are getting interesting. The start of the code is as above, and it consists of the standard 
QDOSMSQ job header followed by a version number for the utility - which is, currently, unused in 
the remainder of the code - followed by the defining of two buffers. One buffer is 64 bytes long for 
the file header and the other is 8 for the XTcc Trailer Record data. 


aCheckt hic 
Ohno mothe ty 
; exit from EW (but 


stack on entry. We only require NUMCHAN channels — any 


than NUMCHANS will result 


sadly , not from EX). 


in a BAD PARAMETER error on 


checkStack 


cmpi.w 


beq.s 
moveq 
bra.s 


#NUMCHANS, ( a7 ) : 
readHeader : 
#err_bp ,d0 ; 


errorExit g 


One channel is a must 
Ok 

Oops 

Bale out 


Listing 3.4: XTcc - Channel Checking 


The first check made by the code is to ensure that it was called with a single file channel on the 
stack. The utility wil exit with a bad parameter error if this is not the case. 


; READ HEADER = read 


2 A0ORE = Channel ide (Rreserved) 


Aleie=sButker saddinessh 
5 Il = Not used. 


the file header for 


the given channel. 


(1 past end of buffer on return) 


(Size Mot bine read) 
7 D2.We— sButtern Nemeth (Preserved ) 
; D3.W = Timeout. 


(Preserved ) 


readHeader 


moveq 
moveq 
moveq 


=> throughout 


move. | 
lea 
move. | 
move .w 
trap 
ESE ell 
bne.s 
cmp .w 
beq.s 
moveq 
bra.s 


#fs_headr ,d0O : 
#64 ,d2 3 
#timeout ,d3 : 


sourceld(a7) ,a0 : 
rh_buffer ,al : 


do 4 
errorExit 
dl ,d2 ; 
checkExecutableType ; 
#err_nec ,d0O a 
errorExit s 


Reading the header 
Buffer maximum size 
Infinity is preserved 


Input channel ID — preserved 
Header buffer address 
Preserve buffer address 
Buffer maximum length 
Do it 

Check ‘errors 

Oh dear! 

Successful read? 

Yes 

Not Complete 

Depart 


Listing 3.5: XTcc - Read the File Header 


Reading the passed file’s header is next. There should be 64 bytes to be read and this is checked on 
return form the trap. If we didn’t get exactly 64 bytes, we bale out with a not complete error. 


119 
120 
121 
122 
123 
124 
125 
126 
127 


128 
129 
130 
NE 
132 
133 
134 
135 
136 
137 
138 
139 
140 
141 
142 
143 
144 
145 
146 
147 
148 
149 
150 
151 
152 


153 
154 
133 


15 


Interestingly, I noticed that in QPC version 4.0.5, if the file was ever renamed, the file header 
appears to retain the original name. That caused me no end of fun' when I was debugging - reading 
the header for one file, and getting a completely different file’s header, or so it seemed. 


s Cee ii the wile iS allireachy executable, Ii SO, Giieily exit as we 
; have nothing to do. Cross compiled files do not come set to be 
2 executaiolle . 


checkExecutableType 


cmpi.b #exeType,fileType(a3) ; Buffer start is in a3 now 
beq.s allDone Exe cutabiles—s nothing stomdo 


Listing 3.6: XTcc - Is the File Executable? 


If the header was happily read, the code above makes sure that the file’s type is not already 
executable. If it is, the utility will simply exit as there is nothing more to do. Cross compiled files 
don’t come with the file’s type set to executable. 


4 ina cross compiled tile there iss a pain sol Won words) at the very. 
7; end of the fille These are) Xice followed by the data space for 
; QDOSMSQ. 


; FS_POSAB: 
AOR = Chianniel mids: (Preserved ) 
5 ANIL IL = Ion wseal. (Corrupted !) 
A IDI JL = lille POSiii@M . (New file position on return) 
aD Se We— salinneouite (Preserved ) 
setFileToXTcc 
moveq #fs_posab , dO ; Position absolutely 
move.!1 fileSize(a3),dl Ger ile ize 
subq.1 #8,dl 5 IPoimt AE Mee IkOCcein@m ain iillle 
move.!1 dl1,d2 ; Save required position 
trap #3 DOM it 
PR 6 Il do Ok? 
bne.s errorExit ; Oops! 
cmp. | dil ,d2 ; Actual = requested position? 
beq.s readXTccData eS 
moveq #err_or ,d0 ; Out of range 
Divas errorExit ae bialie out 


Listing 3.7: XTcc - Locating the XTcc Trailer 


The header was read and the file isn’t executable. The next step is to position the file’s read pointer 
at 8 bytes back from the very end of the file. This is where we expect to find the XTcc Trailer 
Record that we need. If we fail to set the position exactly as requested, we bale out with an out of 
range error. 


> 


; Read the final 2 words from the input file. 


'For certain values of ‘fun’! 


156 
Laz 
158 
159 
160 
161 
162 
163 
164 
165 
166 
167 
168 
169 
170 
171 
172 
Eis 
174 
175 
176 


Ley 
178 
179 
180 
181 
182 
183 
184 
185 
186 
187 
188 
189 
190 
191 
192 
193 
194 
195 
196 
ey 
198 
199 
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7 LOSESURG: 
a A0r le — Channel ead (Preserved ) 
JN Pes Budihe readiness (Old Al + returned D1.W) 
Ditie— Not iWsede (Number of bytes read) 
2 IDA AW = IDG Sie. (Preserved ) 
Se We—salinmeouite (Preserved ) 
readXTccData 
moveq #io_fstrg ,d0 ; Fetch bytes 
moveq #8 ,d2 ; Bytes we want 
lea xtcc_buffer ,al ; Buffer address 
move.!1 al,a2 ; Save buffer address 
trap #3 DO wsit 
SE all do 
bne.s errorExit ; Oops! 
cmp .w d2,dl ; Did we get 8 bytes? 
beq.s checkXTccFound aes 
moveq #err_fe ,d0O ; —16 File Error 
bra.s errorExit ; Bale out 


Listing 3.8: XTcc - Read the XTcc Trailer Record 


Next up, we read the 8 bytes that make up the XTcc Trailer Record. If this fails, or we do not read 
exactly 8 bytes, bale out with a file error message. 


’ 


; We should have ’XTcc’ in the buffer plus the dataspace required. 


checkXTccFound 


cmpi.l #"XTcc" ,(a2)+ 7 Gov they i lacy? 
bne.s noXTccFound ; Nope 


> 


; We have the data we want, copy the dataspace into the file header 
and stnenmimakesnt hem ialicumexccultalbilicn, 


> 


extractDataSpace 
move.1 (a2),fileData(a3) ; Copy the value over 
move.b #exeType, fileType(a3) ; Make executable 
bra.s writeHeader WW Tite thie hicadem back 


> 


| \We GbiGln (i site! ile Ree” ilews eu ide ene! Grr wie jie. 


noXTccFound 
moveq #err_nf ,d0O ; Not found 
bra.s errorExit ; Bale out 


Listing 3.9: XTcc - Setting the Header Data 


Assuming that we managed to read it, does the XTcc Trailer start with the XTcc flag, which happens 
to be the string "XTcc" in that letter case. In the event that we didn’t find that flag, we will exit 
with a not found error. 


200 
201 
202 
203 
204 
205 
206 
207 
208 
209 
210 
211 
212 
213 
214 
2i5 


7 


If the flag is found, copy the last 4 bytes of the XTcc Trailer into the file’s header to set the data 
space, and set the file’s type to be an executable file. 


5 Wale tne wwe IMneEicler iter Wie even) CliAmMell . 


7 AOE = Channels lide (Preserved) 

7 Ale = Buen saddmnessr (Corrupted ) 

= 1D) = Not used. (Length of set header) 

= D2 = Notaused™ (Preserved ) 

7) D3EW) = imeoute (Preserved ) 

writeHeader 
moveq #fs_heads ,d0O ; Write the header 
move.1 a3,al + Header butter 
trap #3 eDOm iit 
ESE g ll do ; Ok? 
bne.s errorExit ; Sadly, not! 


Listing 3.10: XTcc - Writing the Header 


We can now write the file header back to the medium. This will set the data space and make the file 
executable. 


> 


; No errors , exit quietly back to SuperBASIC. 


allDone 
moveq #0 ,d0 


; We have hit van) error so we copy the code to D3 then (exit vila a 
; forcible removal of this job. EXEC_W/EW will display the error in 
; SuperBASIC, but EXEC/EX will not. 


errorExit 


move.l1 d0,d3 ; Error code we want to return 


> 


Tele myselimwhenwani errors wasmideLectcdsmOnnalse Oh 


2 


suicide 
moveq #mt_frjob ,d0 ; This job will die soon 
moveq #me,dl 
trap #1 


Listing 3.11: XTcc - Termination 


The end. This is where we exit from the utility either with an error code or not. 


Be aware that you will only ever see the error code or message, when you call the utility with EW 
as EX will not hang around to find out what the error, if any, was - it creates the job, activates it, 
and bales out. Only EW hangs around to the bitter end! 


In the last issue, we took a very long look at the new and upgraded instructions that are now 
available when using an MC68020 processor as found in QPC - and possibly, in other emulators 
too. The old BBQL’ uses an MC68008 and cannot cope with the new stuff. 


To assemble these 62020 instructions, you need a copy of Gwass available from 
This article continues our look at new features of the MC68020. 
Here are the subjects I will cover in this issue, in relation to the 68020: 


e The new format Status Register 
e The various Control Registers used by the MOVEC instruction. 


Status Register 

The status register looks like the following in the MV68020: 
| Bit | 
| 15] 14] 13]12]11|10]9|8|]7/6/5]4/3]2]1]0| 
[T [To] S| MJ - |b |b | bo] - X|N|Z/ Vic] 


Table 4.1: MC68020 Status Register 


Trace Bits 7, and 7) 


In the status register for the MC68020 we have now got an extra Trace bit - bit 14 - known as To. 
The original (MC68008) Trace bit, bit 15, is now known as the T; bit. Between the two Trace bits, 


1Black Box QL 
2 
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better tracing can take place, as follows: 


e 00 - When both Trace bits are zero, no tracing takes place. 

e O01 - When T; is clear and To is set, tracing takes place on a change of program flow - a 
branch, jump or subroutine call. 

e 10- When T; is set and To is clear, tracing happens after every instruction. This is the tracing 
mode we are used to on the MC68008. 

e 11 - Undefined. Probably best avoided! 


4.1.2 Supervisor Master and Interrupt Modes 


4.2 


4.2.1 


In addition to the extra Trace bit, there is a new Master bit as well. Bit 12 is the new Master bit. 


On the MC68020, Supervisor mode is now split into two sub modes - master and interrupt. When 
the S and M bits are set then the processor is running in Master mode and uses the new Master 
Stack with the Master Stack Pointer in A7. (MSP(A7’)) 


When the S bit is set, and the M bit is clear, then the processor is running in Interrupt mode and 
uses another new stack, the Interrupt Stack, with A7 being the Interrupt Stack Pointer. (ISP(A7’)) 


The only difference between the two modes is the different stack pointer in use in register A7. 


Control Registers and MOVEC 


On the MC68020 we have the following control registers: 


Control Register | Description 
SFC Source Function Code 
DFC Destination Function Code 
USP User Stack Pointer 
VBR Vector Base Register 
CACR Cache Control Register 
CAAR Cache Address Register 
MSP Master Stack Pointer 
ISP Interrupt Stack Pointer 


Table 4.2: MC68020 Control Registers 


SFC and DFC- Source and Destination Function Code 


The alternate function code registers contain 3-bit function codes. Function codes can be considered 
extensions of the 32-bit logical address that optionally provides as many as eight 4-Gbyte address 
spaces - potentially increasing the 32 bit address bus to 35 bits. 


The processor automatically generates function codes to select address spaces for data and programs 
at the user and supervisor modes. 


Certain instructions use SFC and DFC to specify the function codes for operations. 


The processor has three pins named FCO, FC1 and FC2. When the processor reads or writes from 
memory, these pins reflect information about the state of the processor. 


They show the state of the processor - is it running in user or supervisor mode - and whether it is 


4.2.2 


4.2.3 


4.2.4 


4.2 Control Registers and MOVEC 2] 


accessing data or instructions in memory. 


The function codes are often used by external Memory Management Units (MMU) to protect 
various sections of memory. To the best of my knowledge, the QL doesn’t have an MMU. 


VBR - vector Base Register 


The VBR is a 32 bit register which contains the base address of the exception vector table in 
memory. The displacement of an exception vector adds to the value in this register, which accesses 
the vector table. 


On the MC68008, the exception table always lived at address 0, however, from the MC68010 
onwards, the vector table still lives at address 0, but after a processor reset, the VBR can be adjusted 
to any desired location - provided that it can be addressed by a single 32 bit register. 


CACR and CAAR - Cache Conirol 


Many programs spend a lot of time executing loops. While within these loops, they execute the 
same (small) set of instructions over and over again. Each time the processor needs to execute an 
instruction, it must read it from memory. 


There is a 256 byte instruction cache built in to the MC68020 (but probably not built in to the virtual 
MC68020 using in QPC, for example) which contains the most recently executed instructions. 


In the case of a loop, the processor doesn’t need to access memory to read the instructions more 
than once, in theory. When an instruction is read, it is stored in the cache and if executed again, 
will be read from cache which is much much quicker than reading from memory. 


This is not always appropriate though, so the processor has the ability to enable, disable and 
otherwise manipulate the cache through the use of the CACR and CAAR control registers. These 
registers are 32 bits wide. 


The use of these registers is beyond the scope of this series. They are unlikely to be mentioned ever 
again - except in passing, maybe! 


USP MSP and ISP - Stack Pointers 


In normal user programs, the processor runs in user mode and the stack pointer in A7 is the USP or 
User Stack Pointer. 


In Supervisor mode, a different stack is in use, usually limited in size, and on the BBQL, A7 was 
then known as the SSP or Supervisor Stack Pointer. 


On the MC68020 we have two submodes for Supervisor mode, and each one can have a different 
stack area and A7 will be set accordingly to the Master Stack Pointer (MSP) or the Interrupt Stack 
Pointer (ISP) depending on the settings of the S and M bits in the Status Register. 


If S is set and M is clear, the ISP is in A7, while the MSP is in A7 if both bits are set. 


The front cover image on this ePeriodical is taken from the book Kunstformen der Natur by German 
biologist Ernst Haeckel. The book was published between 1899 and 1904. The image used is of 
various Polycystines which are a specific kind of micro-fossil. 


I have also cropped the image for use on each chapter heading page. 


You can read about Polycystines on and there is a brief overview of the above book, 
also on , which shows a number of other images taken from the book. (Some of which I 
considered before choosing the current one!) 


Polycystines have absolutely nothing to do with the QL or computing in general - in fact, I suspect 
they died out before electricity was invented - but I liked the image, and decided that it would make 
a good cover for the book and a decent enough chapter heading image too. 


Not that Iam suggesting, in any way whatsoever, that we QL fans are ancient. 


